Using Git and GitHub in the Scottish Government
 

Alice Byers, Data Innovation Team

Scottish Government

Aims

  • These slides aim to demonstrate the use of Git and GitHub in the Scottish Government when working in the SCOTS network.

  • An understanding of the concepts of version control, Git and GitHub is assumed. More information can be found in the Introduction to Version Control slides.

  • Further guidance and resources for using version control on SCOTS are available on the Statistics Group sharepoint site.

Contents

Git setup

Install Git

  • Make an iFix request for “Git version 2.21.0.windows.1”

  • Git is a free and open-source software and therefore does not incur a cost to install

Git Bash

  • Git Bash is a command line interface for using Git

  • It is installed with Git

Git Bash

  • Some basic commands include:

    • pwd; prints present working directory

    • ls; lists files contained in working directory

    • cd <filepath>; changes working directory

  • Git Bash cheat sheet

  • ONS Learning Hub has further training on Command Line Basics

Set name and email

  • Your name and email is linked to every commit you make using Git and cannot be changed retrospectively, therefore it is important to do this.

  • If you plan to use GitHub, make sure your user name and email address match those associated with your GitHub account.

To do this in Git Bash, run:

git config --global user.name alicebyers5
git config --global user.email alice.byers@gov.scot

To check this has worked:

git config --global user.name
alicebyers5

git config --global user.email
alice.byers@gov.scot

Summary

  • Install Git via iFix

  • Set name and email address in Git Bash

Git workflow

Example project folder


Open Git Bash in working directory

  • Right click in working folder and select ‘Git Bash here’

  • Open Git Bash from Windows start menu

  • Use cd command to change directory to your working folder

Initiate Git respository

  • Run git init to initiate Git. This will create a .git folder within your project. (Note: you only need to do this once per project.)

Create a gitignore file

  • A gitignore file defines what files should not be tracked by Git. This is especially important if you plan on using GitHub as sensitive information should not be made available there.

  • Generally, the following should be ignored:

    • Data files

    • Passwords or credentials

    • Code that contains sensitive information

    • Configuration files

Create a gitignore file

To tell Git to ignore these files:

  • Create a new file in your directory called .gitignore. This can be done in the usual way in File Explorer, or by using the touch command in Git Bash.

  • Open the .gitignore file in a text editor (or R) and add names of folders and files to be ignored.

    • This is a good example gitignore that contains many common data and R files. Copy the contents to the file you’ve just created.

git status

  • Use git status to show a summary of your Git repository - run this often to check that your other git commands have done what you expect them to do

  • Notice that data.csv is not listed here. This is because we have told Git to ignore csv files in the gitignore.

git add

  • Use git add to ‘stage’ files for the next commit

    • Either list the files you’d like to stage; e.g. git add code.R, or

    • To stage all tracked files, use a full stop; e.g. git add .

git add

  • Use git status to check that the correct files have been staged

  • Files names are now coloured green and listed under ‘changed to be committed’

git commit

Your first commit

  • Running git status again shows that there are no further changes to commit

Your first commit

  • Running git log --oneline will give a short summary of the commit history

Make a change

  • Now, let’s make a change to code.R. Add some commented lines to give the script a title and description.

Before

After

Make a change

  • Run git status to check that Git has recognised the change

git diff

  • Run git diff to inspect what changes have been made to code.R. Green text highlights additions and red text highlights deletions.

Stage and commit the change

  • Use git add and git commit to stage and commit the change to code.R.

Stage and commit the change

  • Use git log to view the Git history - there are now two commits

Tips

  • Commit early and often (especially when you’re still learning)

  • Write commit messages that make sense (your future self and colleagues will thank you)

  • Run git status often (especially when you’re still learning)

    • Check which files have changes tracked

    • Check you have staged the correct files

    • Check files that should be ignored are not being tracked (and committed!)

Summary

  • Make a change

  • git add

  • git commit

  • git status often

Using Git with RStudio Integration

RStudio

  • Not all Git functionality is available from RStudio, but it can be more user-friendly and convenient if you’re working with R

  • Changes are listed in the Git pane (usually in the top right window)

Open the commit window

  • Click the ‘Commit’ button to open up the commit window

Commiting a change from RStudio

  • Like Git Bash, you need to both stage and commit the change

  • To stage, tick the box next to each file you’d like to add (top-left pane)

  • To commit, enter a message and click ‘Commit’ (top-right pane)

GitHub and
Data Science Scotland

Create GitHub account

  • Use your work email address

    • Note that you can associate multiple email addresses with your account. Just made sure you author commits for work projects with your gov.scot address.

  • Enable two-factor authentication

  • Add a (work appropriate) photo and username

  • Add your contact details and employer

  • Make your gov.scot email address public on your profile

Join Data Science Scotland organisation

  • Work projects should all be hosted from the Data Science Scotland organisation

  • Request to join the organisation

  • Once your request has been accepted, you will be free to create Git repositories in Data Science Scotland

Create a repository

Create a repository

  • Select Data Science Scotland as owner for work projects

  • Give the repository a name

  • Choose whether to make your repository public or private

  • Add a README file

  • Click the green ‘Create repository’ button

Using Git with GitHub

Remote repository

  • A ‘remote’ is a version of your Git repository hosted on the internet or network somewhere.

  • This should be thought of as the main place where your repository is stored.

  • Most commonly, GitHub is used to host remote repositories. But, it can also be a folder on an internal shared network.

Remote repository

  • Users take a copy (‘clone’) of the repository from the remote

  • Users regularly ‘push’ their changes back to the remote so other users have access to the latest version

  • Users regularly ‘pull’ from the remote to ensure they are working with the latest version

flowchart TB
  R[Remote]
  R <--> U1((<font size=2>User 1))
  R <--> U2((<font size=2>User 2))
  R <--> U3((<font size=2>User 3))
  
  linkStyle default stroke-width:1px;

Create SSH key (one time setup)

  • Generate an SSH key in Git Bash

    ssh-keygen -t ed25519 -C "your_email@example.com"

    (this should be the email registered with your Github account)

  • Git Bash will ask where you want to create the key. The default location is recommended. (You can find your SSH home in Git Bash by running: echo ~/.ssh.)

  • Git Bash will ask if you want to set a passphrase. This is a local password that will be requested each time you use the key. It is OK not to set a passphrase here by just pressing enter twice.

Add SSH key to GitHub account
(one time setup)

  • Copy the SSH key:

    # Navigate to the directory where you've saved your SSH key
cd ~/.ssh

# Print the contents of the public SSH key file
cat id_ed25519.pub

    Copy the returned value from Git Bash.

  • Add the copied SSH key to your GitHub account

Clone repository from GitHub

  • Now you have an SSH key setup, you should use the SSH URL to clone repositories from GitHub.

  • Click the green ‘Code’ button and under ‘Clone’, select ‘SSH’, and copy the address.

Clone repository from GitHub

  • Open Git Bash and navigate to the directory you’d like to clone the repository to

  • Use git clone to clone the repository

  • Change directory to the cloned repository using cd

Make a change

  • Add a new file

  • git add

  • git commit

Push to GitHub

  • ‘Push’ the commit to GitHub (the remote) using git push

  • Note that git status now says the repository is up to date with origin/main (this is another name for the remote repository)

Push to GitHub

  • The commit is now visible by viewing the GitHub repository

Pull from GitHub

  • ‘Pull’ from GitHub regularly to ensure your local copy of the repository is up to date (especially if other people are also working on the repository)

  • Note that there is now an extra commit when running git log

Summary

  • Use SSH keys to connect to GitHub from Git Bash

  • git push often

  • git pull often

There’s more!

Branches

  • Main branch?

  • Branches allow users to make changes to files without affecting the ‘production-ready’ main branch

  • Allows changes to be peer reviewed before being merged into main branch

  • More information on branching in the Duck book

GitHub features

  • Pull requests and code review

    • Open a pull request to merge a branch and request a code review from a collaborator

  • Issues

    • Keep track of bugs and requested enhancements for future development

  • Projects

    • A task board for planning and tracking work. Integrates with issues and pull requests.

Resources

Contact

Alice Byers, Data Innovation Team

Scottish Government